/**
 * @version 1.0
 * @created 12 Nov 2010
 *
 * CommonDAO
 *
 * Copyright @ 2010 by CES
 * All Rights Reserved.
 * CONFIDENTIAL AND TRADE SECRET
 * 
 */
package com.ces.knacky.framework.dao;

import java.util.List;

import com.ces.knacky.framework.model.IEntity;
import com.ces.knacky.framework.services.CommonService;

/**
 * This is a common DAO class which provide CRUD operation services. It is common interface for all
 * data access objects. 
 * 
 * @see HibernateDAO
 * @see CommonService
 * @see IEntity
 * @author bipul_sinha
 *
 */
public interface CommonDAO {
    
    /**
     * It is used to add/save an object. The object should be of type IEntity. 
     * @param 	entity
     * 			Represents object to be added/saved to the database.
     * @return	boolean
     * 			Returns true if the object is added successfully. 
     */
    boolean add(IEntity entity);
    
    /**
     * It is used to save a transient IEntity object and return persistent object after database
     * operation.
     * 
     * @param 	IEntity
     * 			Transient object to be saved.
     * @return	IEntity
     *   		Persistent Id of the object after save operation.
     */
	Integer save(IEntity entity);
    /**
     * It is used to update/modify an entity. It takes entity as a parameter to be updated.
     * 
     * @param 	entity
     * 			Represents entity to be modified/updated in the database.
     * @return	boolean
     * 			Returns true if the object is updated successfully. 
     */
    boolean update(IEntity entity);
    
    /**
     * It is used to physically delete object from the database. It takes entity object and Id for
     * deletion.
     *   
     * @param 	entity
     * 			Represents the entity to be physically deleted.	
     * @return	boolean
     * 			Returns true if the object is deleted successfully. 
     */
    boolean delete(IEntity entity);
    /**
     * It is used to load the persistent object from the database. It takes Id and the name of 
     * entity to be loaded.
     *  
     * @param 	clazz
     * 			Represents fully qualified name of the class of whose entity to be loaded.
     * @param 	Id
     * 			Represents Id of the entity to be loaded.
     * @return	IEntity
     * 			Represents the loaded persistent entity. 
     */
    IEntity load(Class<? extends IEntity> clazz, Integer Id);
    
    /**
     * It takes an HQL query as a parameter and return list of objects.
     *  
     * @param 	query
     * 			Represents HQL query to be executed.
     * @return	List
     * 			Represents list of IEntity objects.
     */
    List<? extends IEntity> list(String query);
    
    /**
     * It is used to fetch results from the database using description field. It returns list of 
     * objects whose description matches in the DB with the specified parameter.
     * 
     * @param 	name
     * 			Represents POJO class from where the description will be matched. 
     * @param 	description
     * 			Represents the value of description field whose objects needs to be returned.
     * @return	List
     *			Represents list of objects fetched from the database. 			
     */
    List<? extends IEntity> findByDescription(Class<? extends IEntity> name, String description);
    
    /**
     * It is used to fetch only the first object which matches the criteria. It is similar to 
     * findByDescription() method however returns only the first object unlike list of objects.
     *  
     * @param 	name
     * 			Represents POJO class from where the description will be matched.
     * @param 	description
     * 			Represents the value of description field whose objects needs to be returned.
     * @return	IEntity
     * 			Represent the first object fetched from the DB.
     */
    IEntity findFirstByDescription(Class<? extends IEntity> name, String description);
    
	/**
	 * Method used to prepare query.
	 * 
	 * @param 	statement
     * 			Represents update query to be executed. 
     * @return	int
     * 			Represent number of records updated.
     */
    int batchUpdate(String statement);
}
